QuickTime Streaming

Media Packetizer Functions

The following functions can be implemented by media packetizer components. Most of these functions must be implemented in your component, but some are optional, as noted in the discussion section of the optional functions.

RTPMPInitialize

The RTPMPInitialize function is called to initialize your media packetizer component. RTPMPInitialize will be called after your component is opened, and after the RTPMPPreflightMedia call, but before it is sent any data to packetize.



 
ComponentResult RTPMPInitialize (

                     RTPMediaPacketizer rtpm,

                     SInt32 inFlags);

rtpm: The component instance of your media packetizer
inFlags: A signed 32-bit integer containing the flags for your packetizer at start-up. Defined flags are:kRTPMPRealtimeModeFlag - your packetizer is being called in a real-time situation (for example, live broadcasting)

DISCUSSION

The calling component must call RTPMPInitialize before any RTPMPSet calls.

RTPMPPreflightMedia

This function is called to determine whether your packetizer can work with a given media type and sample description. Return noErr if you can packetize this type of data. Return qtsUnsupportedFeatureErr if you cannot.



 
ComponentResult RTPMPPreflightMedia (

                     RTPMediaPacketizer rtpm,

                     OSType inMediaType,

                     SampleDescriptionHandle inSampleDescription);

rtpm: The component instance of your media packetizer
inMediaType: The media type (such as 'vide')
inSampleDescription: The sample description
function result: Return noErr if you can packetize this type of data. Return qtsUnsupportedFeatureErr if you cannot.

DISCUSSION

This function will be called before you are asked to packetize any data. This function must be implemented by your packetizer.

RTPMPIdle

This function is called periodically in the application program's event loop to allocate time to your media packetizer. If your packetizer operates synchronously, doing all of its work in the RTPMPSetSampleData function, the RTPMPIdle function does nothing. If your packetizer operates asynchronously, it sets outFlags to kRTPMPStillProcessingData in RTPMPSetSampleData and processes data during RTPMPIdle. Set outFlags to 0 if you have processed all the data passed to you in the last RTPMPSetSampleData . Set outFlags to kRTPMPStillProcessingData if you need the application to call RTPMPIdle again.



 
ComponentResult RTPMPIdle (

                     RTPMediaPacketizer rtpm,

                     SInt32 inFlags,

                     SInt32 *outFlags);

rtpm: The component instance of your media packetizer
inFlags: There are currently no defined flags
outFlags: On return, contains a pointer to a signed 32-bit integer that holds any flags from your packetizer. Defined flags are: kRTPMPStillProcessingData Set this flag if there is still data in your queue to be processed. The calling application will call RTPMPIdle repeatedly until this flag is not returned. If all data in your queue has been processed, set outFlags to.

DISCUSSION

The packetizer can use this time to process the data in its buffer. Data is placed in the buffer by the RTPMPSetSampleData function. If the data has not all been processed, the RTPMPSetSampleData function sets outFlags to kRTPMPStillProcessingData ; this causes the calling application to call RTPMPIdle. The RTPMPIdle function can also set outFlags to kRTPMPStillProcessingData if it needs more time. The calling application will call RTPMPIdle repeatedly until you set outFlags to 0.

Your packetizer may make calls to the packet builder in response to this call.

RTPMPSetSampleData

This function is called to provide sample data to your media packetizer component. Packetize the data according to your own algorithm and pass it to the selected packet builder. If you can process all the data immediately, set outFlags to 0. If you need more data to complete a packet, set outFlags to kRTPMPWantsMoreDataFlag . If you need more time, set outFlags to kRTPMPStillProcessingData and continue processing in RTPMPIdle.



 
ComponentResult RTPMPSetSampleData (

                     RTPMediaPacketizer rtpm,

                     const RTPMPSampleDataParams *inSampleData,

                     SInt32 *outFlags);

rtpm: The component instance of your media packetizer
inSampleData: A pointer to the sample data
outFlags: If you have processed all the data, set outFlags to 0. If you need more data to complete a packet, set outFlags to kRTPMPWantsMoreDataFlag . If you need more time, set outFlags to kRTPMPStillProcessingData and continue processing in RTPMPIdle.
function result: qtsBadDataErr - the packetizer cannot process the given data



 
/* flags for RTPMPSampleDataParams*/

enum {

    kRTPMPSyncSampleFlag= 0x00000001

};      

struct RTPMPSampleDataParams {

    UInt32                      version;

    UInt32                      timeStamp;

    UInt32                      duration;           /* 0 if not specified*/

    UInt32                      playOffset;         /* 0 if not specified*/

    Fixed                       playRate;

    SInt32                      flags;

    UInt32                      sampleDescSeed;

    Handle                      sampleDescription;

    RTPMPSampleRef      sampleRef;

    UInt32                      dataLength;

    const UInt8 *       data;

    RTPMPDataReleaseUPP releaseProc;

    void *                      refCon;

};



 
typedef struct RTPMPSampleDataParamsRTPMPSampleDataParams;

version: Version of the data structure. Currently always 0.
timeStamp: RTP time stamp for the presentation of the sample data. This time stamp has already been adjusted by edits, edit rates, etc.
duration: Duration (in RTP time scale) of the sample.
playOffset: Offset within the media sample itself. This is only used for media formats where a single media sample can span across multiple time units. QuickTime Music is an example of this, where a single sample spans the entire track. For most video and audio formats, this will be 0.
playRate: 1.0 (0x00010000) is normal. Higher numbers indicate faster play rates. Note that timeStamp is already adjusted by the rate. This field is generally of interest only to audio packetizers.
flags: kRTPMPSyncSampleFlag is set if the sample is a sync sample (key frame).
sampleDescSeed: If the sample description changes, this number will change.
sampleDescription: The sample description for the given media sample
sampleRef: Private field.
dataLength: Size of media data
data: Pointer to media data
releaseProc: If set, you need to call it when you are finished with the sample data.
refCon: Pass to releaseProc

DISCUSSION

This routine is called to pass media data to a media packetizer. Note that the caller owns the RTPMPSampleDataParams struct pointed to by inSampleData . Your media packetizer must copy any fields of the struct that it wants to keep. The caller will maintain only the media data poionted to by the data field in the struct until you call the release proc.

Your media packetizer must call the release proc when done with the media data.

Calling RTPMPSetSampleData adds data cumulatively to any previous calls to RTPMPSetSampleData . The data can contain any number of samples (1 or more), or a partial sample.

Set outFlags to 0 if your packetizer is able to finish packetizing the sample data, or kRTPMPWantsMoreDataFlag if it needs more data to build a packet. Set outFlags to kRTPMPStillProcessingData if you need more time. This will cause a series of calls to RTPMPIdle, which grants time to your packetizer in order to process the data passed in RTPMPSetSampleData .

Your packetizer may make calls to the packet builder in response to this call.

RTPMPReset

Stop packetizing your current input, set your packetizer's state to idle, and flush your input buffer. Reset your packetizer's state as if it had just been opened and initialized.



 
ComponentResult RTPMPReset (

                     RTPMediaPacketizer rtpm,

                     SInt32 inFlags);

rtpm: The component instance of your media packetizer
inFlags: A signed 32-bit integer containing any flags you being passed to the media packetizer. There are currently no defined flags.

DISCUSSION

Stop the media packetizer and flush its input buffer. This function is normally called to stop transmitting immediately, when skipping forward or backward in the stream, for example, or if the network data connection is interrupted.

RTPMPSetInfo

This function is called to set any one of several parameters for a media packetizer.



 
ComponentResult RTPMPSetInfo (

                     RTPMediaPacketizer rtpm,

                     OSType inSelector,

                     const void *ioParams);

rtpm: The component instance of the media packetizer
inSelector: A selector for the type of information to set. RTPMPSetInfo selectors can be:; Your packetizer can be called with these selectors even if it indicated that it couldn't handle the given characteristic in its 'pcki' resource.
ioParams: A pointer to a data structure of the appropriate type for the information being passed.
function result: Return qtsBadSelectorErr if you do not support the selector.

DISCUSSION

This function is used to pass track-level information about the media track to be packetized, such as track ID, layer, and transformation matrix. Return qtsBadSelectorErr unless your packetizer is able to transmit this kind of data to your reassembler for use in the client movie.

RTPMPGetInfo

This function is used to get information of various types from your media packetizer. You will need to return information as a data structure of the appropriate type for the requested information.



 
ComponentResult RTPMPGetInfo (

                     RTPMediaPacketizer rtpm,

                     OSType inSelector,

                     void *ioParams);

rtpm: The component instance of the media packetizer you want information from.
inSelector: The selector for the type information requested. Any of the selectors used with RTPMPSetInfo can be used with RTPMPGetInfo. The following additonal selectors are defined for RTPMPGetInfo only:



 
/* info selectors - get only */

kRTPMPPayloadTypeInfo  ('rtpp'),/* RTPMPPayloadTypeParams* */

kRTPMPRTPTimeScaleInfo  ('rtpt'),/* TimeScale* */

kRTPMPRequiredSampleDescriptionInfo   ('sdsc'), 

    /* SampleDescriptionHandle* */

kRTPMPMinPayloadSize  ('mins'),

    /* UInt32*, doesn't include rtp header; default is 0 */

kRTPMPMinPacketDuration  ('mind'), 

    /* UInt3* in milliseconds; default is no min */

kRTPMPSuggestedRepeatPktCountInfo   ('srpc'),/* UInt32* */

kRTPMPSuggestedRepeatPktSpacingInfo   ('srps'), 

    /* UInt32* in milliseconds */

kRTPMPMaxPartialSampleSizeInfo   ('mpss'),/* UInt32* in bytes */

kRTPMPPreferredBufferDelayInfo   ('prbd') /* UInt32* in milliseconds */

The kRTPMPPayloadTypeInfo selector requires you to fill out an RTPMPPayloadTypeParams structure, which describes the payload being used.



 
/* flags for RTPMPPayloadTypeParams */

enum {

    kRTPMPPayloadTypeStaticFlag= 0x00000001,

    kRTPMPPayloadTypeDynamicFlag = 0x00000002

};      



struct RTPMPPayloadTypeParams {

    UInt32                      flags;

    UInt32                      payloadNumber;

    short                       nameLength;         /* in: size of payloadName buffer 

(counting null terminator) -- this will be reset to needed length and paramErr returned if too 

small */

    char *                      payloadName;    /* caller must provide buffer */

};



 
typedef struct RTPMPPayloadTypeParams RTPMPPayloadTypeParams;

If the flags field of the structure is kRTPMPPayloadTypeStaticFlag , then the payloadNumber field contains the RTP payload number; if the flags field of the structure is kRTPMPPayloadTypeDynamicFlag , then the payloadName field contains the name of the dynamic payload encoding being used. The caller must allocate this payloadName field. You need to copy the payload type string to the buffer pointed to by payloadName (a null-terminated string). When RTPMPGetInfo is called, RTPMPPayloadTypeParams.nameLength will be the available size of the input buffer (specified by payloadName ). If this size is too small for the payload identifier, set nameLength to the size of the buffer you need (including the null terminator) and return paramErr . This will cause QuickTime to reallocate the buffer and call your packetizer again.

kRTPMPRTPTimeScaleInfo: return the RTP timescale used by this packetizer if the time scale must be a specific value; otherwise, returns an error for this selector.
kRTPMPRequiredSampleDescriptionInfo return a handle to a sample description specifying that only: data with the given sample description is supported; if no such sample description exists, returns an error for this selector.
kRTPMPMinPayloadSize: Return the minimum payload size of packets allowed by this packetizer (UInt32).
kRTPMPMinPacketDuration: Return the minimum packet duration allowed by this packetizer (UInt32, in milliseconds).
kRTPMPSuggestedRepeatPktCountInfo: Return the suggested number of repeat packets to send for this media (UInt32). This will typically be 0 for audio or video, nonzero for text or MIDI.
kRTPMPSuggestedRepeatedPktSpacingInfo: Return the suggested temporal distance between repeat packets (UInt32, in milliseconds).
kRTPMPMaxPartialSampleSizeInfo: Return the size of the largest partial sample your packetizer can accept (UInt 32 in bytes).
kRTPMPPreferredBufferDelayInfo: Return the preferred buffer delay for your packetizer (UInt32, in milliseconds).
ioParams: A pointer to a data structure of the appropriate type to hold the information requested.
function result: qtsBadSelectorErr -- the selector is not supported, or an appropriate default value should be used.

DISCUSSION

This function can be called at any time. Return qtsBadSelectorErr for any selector you do not support. Otherwise, return the requested data in ioParams .

RTPMPSetTimeScale

Sets the time scale your media packetizer will use. The time scale is the number of time units that pass in one second (when the media is playing at a rate of 1). The timescale must be set before any calls are made to RTPMPSetSampleData .



 
ComponentResult RTPMPSetTimeScale (

                     RTPMediaPacketizer rtpm,

                     TimeScale inTimeScale);

rtpm: The component instance of your media packetizer
inTimeScale: The timescale to use

DISCUSSION

This timescale gives meaning to the times used in RTPMPSetSampleData .

RTPMPGetTimeScale

Return a pointer to the timescale in use by your media packetizer. The timescale indicates the number of time units that pass in one second (when the media is playing at a rate of 1).



 
ComponentResult RTPMPGetTimeScale (

                     RTPMediaPacketizer rtpm,

                     TimeScale *outTimeScale);

rtpm: The component instance of your media packetizer
outTimeScale: Return the timescale in use by your packetizer

DISCUSSION

The timescale is set by in RTPMPSetTimeScale.

RTPMPSetTimeBase

This call may be made during set up for a live transmission. It tells your packetizer what time base is in use by the calling application.



 
ComponentResult RTPMPSetTimeBase (

                     RTPMediaPacketizer rtpm,

                     TimeBase inTimeBase);

rtpm: Component instance of your packetizer
inTimeBase: The time base in use for this stream

DISCUSSION

You can query this time base to find out the current time in the stream. Your packetizer should not rely on receiving this call.

RTPMPGetTimeBase

Return the time base passed to you in RTPMPSetTimeBase.



 
ComponentResult RTPMPGetTimeBase (

                     RTPMediaPacketizer rtpm,

                     TimeBase *outTimeBase);

rtpm: The component instance of your media packetizer
outTimeBase: Return the time base passed to you in RTPMPSetTimeBase.

RTPMPHasCharacteristic

This call is made to determine whether your media packetizer has a particular characteristic, such as whether it supports a user settings dialog.



 
ComponentResult RTPMPHasCharacteristic (

                     RTPMediaPacketizer rtpm,

                     OSType inSelector,

                     Boolean *outHasIt);

rtpm: The component instance of your media packetizer
inSelector: A selector for the characteristic. Defined selectors are:; kRTPMPNoSampleDataRequiredCharacteristic - if set, the media packetizer does not require the actual sample data to perform packetization. The caller can pass in nil data pointers instead of pointers to the actual media data (see RTPMPSetSampleData ).; kRTPMPHasUserSettingsDialogCharacteristic - if set, the media packetizer supports the calls RTPMPDoUserDialog , RTPMPGetSettingsIntoAtomContainerAtAtom, and RTPMPSetSettingsFromAtomContainerAtAtom.; kRTPMPPrefersReliableTransportCharacteristic - if set, the packetizer would prefer its data to be sent reliably (such as Text or Music tracks, etc.); kRTPMPRequiresOutOfBandDimensionsCharacteristic - if set, the original visual dimensions of the media data cannot be determined simply by looking at the media packets, and must be transmitted via some other method.
outHasIt: Return a boolean which is true if your media packetizer has this characteristic, false otherwise.
function result: Return qtsBadSelectorErr if your packetizer does not have the given characteristic.

RTPMPSetPacketBuilder

Selects which packet builder your media packetizer will use. A media packetizer always sends its output to a packet builder. The specified packet builder may assemble actual RTP packets, or it may use information about the packet to build a hint track.



 
ComponentResult RTPMPSetPacketBuilder (

                     RTPMediaPacketizer rtpm,

                     ComponentInstance inPacketBuilder);

rtpm: The component instance of your media packetizer
inPacketBuilder: The component instance of the packet builder component to use

DISCUSSION

A media packetizer always sends its output to a packet builder. The packet builder must be set using this call prior to any calls to RTPMPSetSampleData . This function can be used to dynamically change the packet builder your media packetizer uses at any time.

RTPMPGetPacketBuilder

Return the component instance of the packet builder component being used by your media packetizer.



 
ComponentResult RTPMPGetPacketBuilder (

                     RTPMediaPacketizer rtpm,

                     ComponentInstance *outPacketBuilder);

rtpm: The component instance of your media packetizer
outPacketBuilder: Return the component instance of the packet builder component in use by this media packetizer

DISCUSSION

The packet builder in use is set by RTPMPSetPacketBuilder .

RTPMPSetMediaType

Sets the type of media that your media packetizer will process (for example, VideoMediaType or SoundMediaType ). The media type will be set prior to any calls to RTPMPSetSampleData . It will not change after such calls.



 
ComponentResult RTPMPSetMediaType (

                     RTPMediaPacketizer rtpm,

                     OSType inMediaType);

rtpm: The component instance of your media packetizer
inMediaType: The media type, such as VideoMediaType .
function result: qtsBadDataErr -- the given media type is not supported.

DISCUSSION

This function will be called before any calls to RTPMPSetSampleData are made, and will not be called after a call to RTPMPSetSampleData .

RTPMPGetMediaType

Return the media type passed in by RTPMPSetMediaType (such as VideoMediaType or SoundMediaType ).



 
ComponentResult RTPMPGetMediaType (

                     RTPMediaPacketizer rtpm,

                     OSType *outMediaType);

rtpm: The component instance of your media packetizer
outMediaType: Return the media type

DISCUSSION

The media type is set by a call to RTPMPSetMediaType .

RTPMPSetMaxPacketSize

Sets the maximum packet size, in bytes, for packets created by your media packetizer.



 
ComponentResult RTPMPSetMaxPacketSize (

                     RTPMediaPacketizer rtpm,

                     UInt32 inMaxPacketSize);

rtpm: The component instance of your media packetizer
inMaxPacketSize: An unsigned 32-bit integer specifying the maximum size, in bytes, of packets your packetizer may create.
function result: qtsBadDataErr -- inMaxPacketSize is smaller than the the minimum payload size for this media packetizer (the value you return in the RTPMPGetInfo call with the kRTPMPMinPayloadSize selector).

DISCUSSION

The media packetizer must not create packets larger than this value. The limit applies only to the payload data. The maximum packet size will not change during a presentation. Streaming will be most efficient if this value is set to the largest packet size that can traverse the network without being split.

RTPMPSetMaxPacketSize will not be called after calling RTPMPSetSampleData . If RTPMPSetMaxPacketSize is not called, use a default value.

RTPMPGetMaxPacketSize

Return the maximum packet size, in bytes, that your packetizer is set to create.



 
ComponentResult RTPMPGetMaxPacketSize (

                     RTPMediaPacketizer rtpm,

                     UInt32 *outMaxPacketSize);

rtpm: The component instance of your media packetizer
outMaxPacketSize: Return a pointer to a 32-bit integer containing the maximum packet size, in bytes, that the packetizer is set to create.

DISCUSSION

The maximum packet size is set by a call to RTPMPSetMaxPacketSize . If no value has been set, return the default value that your packetizer will use.

RTPMPSetMaxPacketDuration

Sets the maximum packet duration, in milliseconds, that the media packetizer is to use.



 
ComponentResult RTPMPSetMaxPacketDuration (

                     RTPMediaPacketizer rtpm,

                     UInt32 inMaxPacketDuration);

rtpm: The component instance of your media packetizer
inMaxPacketDuration: An unsigned 32-bit integer containing the maximum packet duration in milliseconds.
function result: qtsBadDataErr -- The specified value was smaller than the minimum packet duration this media packetizer can support (the value returned from the RTPMPGetInfo call with the kRTPMPMinPacketDuration selector.)

DISCUSSION

The maximum packet duration will not be changed during a presentation.

RTPMPSetMaxPacketDuration will not be called after any calls to RTPMPSetSampleData . If RTPMPSetMaxPacketDuration is not called, use a default value.

RTPMPGetMaxPacketDuration

Return the maximum packet duration, in milliseconds, currently set for this packetizer.



 
ComponentResult RTPMPGetMaxPacketDuration (

                     RTPMediaPacketizer rtpm,

                     UInt32 *outMaxPacketDuration);

rtpm: The component instance of your media packetizer
outMaxPacketDuration: Return a pointer to a 32-bit integer containing the maximum packet duration, in milliseconds, that the packetizer is set to use.

DISCUSSION

The maximum packet duration is set by a call to RTPMPSetMaxPacketDuration . If a duration has not been set, return the default value that your packetizer will use.

RTPMPDoUserDialog

Obtain media-specific settings from the user through a dialog box.



 
ComponentResult RTPMPDoUserDialog (

                     RTPMediaPacketizer rtpm,

                     ModalFilterUPP inFilterUPP,

                     Boolean *canceled);

rtpm: The component instance of your media packetizer
inFilterUPP: A modal dialog filter which may be used in a call to ModalDialog()
canceled: Return a boolean which is true if the user pressed the cancel button in the dialog box. If this parameter is returned true , the settings prior to calling this function should be retained.

DISCUSSION

This is an optional function.

If a media packetizer supports a user dialog (see RTPMPHasCharacteristic ), it can put up a dialog allowing the user to enter media-specific settings. The settings can be requested by the calling application by calling RTPMPGetSettingsIntoAtomContainerAtAtom, and can be restored or set directly from an application by calling RTPMPSetSettingsFromAtomContainerAtAtom.

This function may be called at any time.

RTPMPSetSettingsFromAtomContainerAtAtom

Sets the media-specific settings of a media packetizer. The data is passed in an atom inside an AtomContainer.



 
ComponentResult RTPMPSetSettingsFromAtomContainerAtAtom (

                     RTPMediaPacketizer rtpm,

                     QTAtomContainer inContainer,

                     QTAtom inParentAtom);

rtpm: The component instance of your media packetizer
inContainer: The AtomContainer that holds the settings atom
inParentAtom: The atom that holds the settings

DISCUSSION

This function should only be called if your media packetizer supports packetizer-specific settings. To determine if a media packetizer supports this function, the application will call RTPMPHasCharacteristic .

You can be asked to return the the packetizer-specific settings through the call RTPMPGetSettingsIntoAtomContainerAtAtom. You can be asked to bring up a dialog which allows the user to change the settings through the RTPMPDoUserDialog call.

RTPMPGetSettingsIntoAtomContainerAtAtom

Return the media-specific setting of a media packetizer. The caller must allocate a QT AtomContainer to hold the returned settings.



 
ComponentResult RTPMPGetSettingsIntoAtomContainerAtAtom (

                     RTPMediaPacketizer rtpm,

                     QTAtomContainer inOutContainer,

                     QTAtom inParentAtom);

rtpm: The component instance of your media packetizer
inOutContainer: The AtomContainer that holds the settings atom.
inParentAtom: The atom that will hold the settings.

DISCUSSION

This function should only be called if the media packetizer supports packetizer-specific settings. To determine if your media packetizer supports this function, the application will call RTPMPHasCharacteristic .

The packetizer-specific settings can be set by through the RTPMPSetSettingsFromAtomContainerAtAtom call. You may be asked to bring up a dialog which allows the user to change the settings through the RTPMPDoUserDialog call.

RTPMPGetSettingsAsText

Return the media-specific settings of a media packetizer as text in a format presentable to the user.



 
ComponentResult RTPMPGetSettingsAsText (

                     RTPMediaPacketizer rtpm,

                     Handle *text);

rtpm: The component instance of your media packetizer
text: Return a handle to a copy of your user settings in text format. The text is formatted as simple array of characters. There is no size byte or null termination. Allocate the handle to fit the text precisely.

DISCUSSION

The packetizer-specific settings can be set by the RTPMPSetSettingsFromAtomContainerAtAtom call. You may be asked to bring up a dialog which allows the user to change the settings through the RTPMPDoUserDialog call.

The RTPMPGetSettingsAsText function expects you to return your user settings as text.